.. _Using NeurEcoRNN:

Tutorial: using NeurEco command line interface for a Discrete Dynamic problem
#############################################################################

**NeurEcoRNN** is the executable used for building, evaluating and exporting **Dynamic** models (**Discrete Dynamic**). The executable can be called directly from a terminal / powershell only after a full installation (the portable version doesn't allow this option).
To call the executable, run the following command:

.. code-block:: shell

	neurecoRNN

which will output:

.. code-block:: text

	Running NeurEco Dynamic version 4.01.1154.0 compiled with MSVC v1928  on Dec  5 2022 @ 15:55:33
	usage: neurecoRNN [-h] [command <parameters>]

	Entry point for neurecoRNN network building and evaluation.

	Commands:
	build <configurationFilename>
	        build a neurecoRNN network from a given input solution/excitation set.

	evaluate <configurationFilename>
	        evaluate a neurecoRNN network from a given input solution/excitation set.

	exportFMU <serialized network full path> <FMU model full path> <ORed platform flag (windows=1, linux=2)>
	        export a serialized network as an FMU file.


	Optional arguments:
	-h, --help   show this message and exit

The following section uses the test case :std:ref:`Temperature forecasting test case`. This test case is delivered with the NeurEco installation package.

To build a **Discrete Dynamic** model using the executable:

* Create a configuration file *.conf* for build, here called *build_configuration_file.conf* (see :std:ref:`Build NeurEco Discrete Dynamic model with the command line interface`). 
  For the test case :std:ref:`Temperature forecasting test case`, the configuration file for build looks as follows:

.. code-block:: javascript

	{"neurecoRNN_build":
	        {
	            "exc_filenames": ["./x_first_year.npy"],
	            "output_filenames": ["./y_first_year.npy"],
	            "validation_exc_filenames": [],
	            "validation_output_filenames": [],
	            "test_exc_filenames": ["./x_second_year.npy"],
	            "test_output_filenames": ["./y_second_year.npy"],
	            "write_model_to": "./TemperatureForecasting.ernn",
	            "write_model_output_to_directory": "",
	            "checkpoint_address": "./TemperatureForecasting.checkpoint",
	            "resume": false,
	            "settings": {
	                "valid_percentage": 30,
	                "min_hidden_state": 1,
	                "max_hidden_state": 0,
	                "steady_state_exc": [],
	                "steady_state_out": [],
	                "input_normalization": {
	                    "shift_type": "mean",
	                    "scale_type": "l2",
	                    "normalize_per_feature": true},
	                "output_normalization": {
	                    "shift_type": "mean",
	                    "scale_type": "l2",
	                    "normalize_per_feature": true}
	                    }
	        },
	}


* Place this configuration file in the same directory as the data of the test case (*x_first_year.npy*, *x_second_year.npy*, *y_first_year.npy*, *y_second_year.npy*), otherwise adjust the relative paths to the data files in the configuration file 

* To launch the build, run the following command in the terminal (opened in the data directory, otherwise adjust the relative path to the configuration file):

.. code-block:: shell

	neurecoRNN build ./build_configuration_file.conf

* The build starts automatically:

.. code-block:: text

  00h00m00s info > Running NeurEco Dynamic version 4.01.1154.0 compiled with MSVC v1928  on Dec  5 2022 @ 15:55:33
  00h00m00s warning > Configuration file has no member 'write_model_output_to_directory', using default value '.'
  00h00m00s info > Reading Dataset...

To evaluate a **Discrete Dynamic** model using the executable:

* Create a configuration *.conf* file for evaluation, here called *eval_configuration_file.conf* (see :std:ref:`Evaluate NeurEco Discrete Dynamic model with the command line interface`). 
  For the test case :std:ref:`Temperature forecasting test case`, the configuration file for evaluation looks, for example, as follows:

.. code-block:: javascript

   {
	    "neurecoRNN_evaluate": {
        "exc_filenames": ["./x_second_year.npy"],
        "init_output_filenames": [],
        "init_exc_filenames": [],
        "ernn_filename": "./TemperatureForecasting.ernn",
        "write_model_output_to_directory": "./EvaluationReults"
    }
	}

* Place this configuration file in the same directory as the data of the test case (*x_first_year.npy*, *x_second_year.npy*, *y_first_year.npy*, *y_second_year.npy*), otherwise adjust the relative paths to the data files in the configuration file 

* To launch the evaluation, run the following command in the terminal (opened in the data directory, otherwise adjust the relative path to the configuration file):

.. code-block:: shell

	neurecoRNN evaluate ./eval_configuration_file.conf

* The model is evaluated on the testing data in *"./x_second_year.npy"*, and the results are saved in a the directory created by NeurEco: *"./EvaluationResults"*.

To export a **Discrete Dynamic** model to the FMU format using the executable (*embed* license is required):

* Run the following command:

.. code-block:: shell

	neurecoRNN exportFMU ./TemperatureForecasting.ernn ./TemperatureForecasting.fmu